home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / gnu / gprof / gpfsrc09.zoo / gprof.txt < prev    next >
Text File  |  1991-06-27  |  37KB  |  867 lines
  1. Info file: gprof,    -*-Text-*-
  2. produced by texinfo-format-buffer
  3. from file: gprof.texinfo
  4.  
  5. This file documents the gprof profiler of the GNU system.
  6.  
  7. Copyright (C) 1988 Free Software Foundation, Inc.
  8.  
  9. Permission is granted to make and distribute verbatim copies of
  10. this manual provided the copyright notice and this permission notice
  11. are preserved on all copies.
  12.  
  13. Permission is granted to copy and distribute modified versions of this
  14. manual under the conditions for verbatim copying, provided that the entire
  15. resulting derived work is distributed under the terms of a permission
  16. notice identical to this one.
  17.  
  18. Permission is granted to copy and distribute translations of this manual
  19. into another language, under the above conditions for modified versions.
  20.  
  21.  
  22.  
  23.  
  24. File: gprof  Node: Top, Prev: Top, Up: (dir), Next: Why
  25.  
  26. Profiling a Program: Where Does It Spend Its Time?
  27. **************************************************
  28.  
  29. This manual describes the GNU profiler `gprof', and how you can use it
  30. to determine which parts of a program are taking most of the execution
  31. time.  We assume that you know how to write, compile, and execute programs.
  32. GNU `gprof' was written by Jay Fenlason.
  33.  
  34. * Menu:
  35.  
  36. * Why::            What profiling means, and why it is useful.
  37. * Compiling::        How to compile your program for profiling.
  38. * Executing::        How to execute your program to generate the
  39.                 profile data file `gmon.out'.
  40. * Analyzing::        How to run `gprof', and how to specify
  41.                 options for it.
  42.  
  43. * Flat Profile::    The flat profile shows how much time was spent
  44.                 executing directly in each function.
  45. * Call Graph::        The call graph shows which functions called which
  46.                 others, and how much time each function used
  47.                 when its subroutine calls are included.
  48.  
  49. * Implementation::    How the profile data is recorded and written.
  50. * Sampling Error::    Statistical margins of error.
  51.                 How to accumulate data from several runs
  52.                 to make it more accurate.
  53.  
  54. * Assumptions::        Some of `gprof''s measurements are based
  55.                 on assumptions about your program
  56.                 that could be very wrong.
  57.  
  58. * Incompatibilities::    (between GNU `gprof' and Unix `gprof'.)
  59.  
  60.  
  61. File: gprof  Node: Why, Prev: Top, Up: Top, Next: Compiling
  62.  
  63. Why Profile
  64. ***********
  65.  
  66. Profiling allows you to learn where your program spent its time and which
  67. functions called which other functions while it was executing.  This
  68. information can show you which pieces of your program are slower than you
  69. expected, and might be candidates for rewriting to make your program
  70. execute faster.  It can also tell you which functions are being called more
  71. or less often than you expected.  This may help you spot bugs that had
  72. otherwise been unnoticed.
  73.  
  74. Since the profiler uses information collected during the actual execution
  75. of your program, it can be used on programs that are too large or too
  76. complex to analyze by reading the source.  However, how your program is run
  77. will affect the information that shows up in the profile data.  If you
  78. don't use some feature of your program while it is being profiled, no
  79. profile information will be generated for that feature.
  80.  
  81. Profiling has several steps:
  82.  
  83.    * You must compile and link your program with profiling enabled.
  84.      *Note Compiling::.
  85.  
  86.    * You must execute your program to generate a profile data file.
  87.      *Note Executing::.
  88.  
  89.    * You must run `gprof' to analyze the profile data.
  90.      *Note Analyzing::.
  91.  
  92. The next three chapters explain these steps in greater detail.
  93.  
  94. The result of the analysis is a file containing two tables, the
  95. "flat profile" and the "call graph" (plus blurbs which briefly
  96. explain the contents of these tables).
  97.  
  98. The flat profile shows how much time your program spent in each function,
  99. and how many times that function was called.  If you simply want to know
  100. which functions burn most of the cycles, it is stated concisely here.
  101. *Note Flat Profile::.
  102.  
  103. The call graph shows, for each function, which functions called it, which
  104. other functions it called, and how many times.  There is also an estimate
  105. of how much time was spent in the subroutines of each function.  This can
  106. suggest places where you might try to eliminate function calls that use a
  107. lot of time.  *Note Call Graph::.
  108.  
  109.  
  110. File: gprof  Node: Compiling, Prev: Why, Up: Top, Next: Executing
  111.  
  112. Compiling a Program for Profiling
  113. *********************************
  114.  
  115. The first step in generating profile information for your program is
  116. to compile and link it with profiling enabled.
  117.  
  118. To compile a source file for profiling, specify the `-pg' option when
  119. you run the compiler.  (This is in addition to the options you normally
  120. use.)
  121.  
  122. To link the program for profiling, if you use a compiler such as `cc'
  123. to do the linking, simply specify `-pg' in addition to your usual
  124. options.  The same option, `-pg', alters either compilation or linking
  125. to do what is necessary for profiling.  Here are examples:
  126.  
  127.      cc -c myprog.c utils.c -pg
  128.      cc -o myprog myprog.o utils.o -pg
  129.  
  130. The `-pg' option also works with a command that both compiles and links:
  131.  
  132.      cc -o myprog myprog.c utils.c  -pg
  133.  
  134. If you run the linker `ld' directly instead of through a compiler such
  135. as `cc', you must specify the profiling startup file
  136. `/lib/gcrt0.o' as the first input file instead of the usual startup
  137. file `/lib/crt0.o'.  In addition, you would probably want to specify
  138. the profiling C library, `/usr/lib/libc_p.a', by writing `-lc_p'
  139. instead of the usual `-lc'.  This is not absolutely necessary, but doing
  140. this gives you number-of-calls information for standard library functions such
  141. as `read' and `open'.  For example:
  142.  
  143.      ld -o myprog /lib/gcrt0.o myprog.o utils.o -lc_p
  144.  
  145. If you compile only some of the modules of the program with `-pg', you
  146. can still profile the program, but you won't get complete information about
  147. the modules that were compiled without `-pg'.  The only information
  148. you get for the functions in those modules is the total time spent in them;
  149. there is no record of how many times they were called, or from where.  This
  150. will not affect the flat profile (except that the `calls' field for
  151. the functions will be blank), but will greatly reduce the usefulness of the
  152. call graph.
  153.  
  154. So far GNU `gprof' has been tested only with C programs, but it ought
  155. to work with any language in which programs are compiled and linked to form
  156. executable files.  If it does not, please let us know.
  157.  
  158.  
  159. File: gprof  Node: Executing, Prev: Compiling, Up: Top, Next: Analyzing
  160.  
  161. Executing the Program to Generate Profile Data
  162. **********************************************
  163.  
  164. Once the program is compiled for profiling, you must run it in order to
  165. generate the information that `gprof' needs.  Simply run the program
  166. as usual, using the normal arguments, file names, etc.  The program should
  167. run normally, producing the same output as usual.  It will, however, run
  168. somewhat slower than normal because of the time spent collecting and the
  169. writing the profile data.
  170.  
  171. The way you run the program---the arguments and input that you give
  172. it---may have a dramatic effect on what the profile information shows.  The
  173. profile data will describe the parts of the program that were activated for
  174. the particular input you use.  For example, if the first command you give
  175. to your program is to quit, the profile data will show the time used in
  176. initialization and in cleanup, but not much else.
  177.  
  178. You program will write the profile data into a file called `gmon.out'
  179. just before exiting.  If there is already a file called `gmon.out',
  180. its contents are overwritten.  There is currently no way to tell the
  181. program to write the profile data under a different name, but you can rename
  182. the file afterward if you are concerned that it may be overwritten.
  183.  
  184. In order to write the `gmon.out' file properly, your program must exit
  185. normally: by returning from `main' or by calling `exit'.  Calling
  186. the low-level function `_exit' does not write the profile data, and
  187. neither does abnormal termination due to an unhandled signal.
  188.  
  189. The `gmon.out' file is written in the program's *current working
  190. directory* at the time it exits.  This means that if your program calls
  191. `chdir', the `gmon.out' file will be left in the last directory
  192. your program `chdir''d to.  If you d